Updated at : Tue Nov 04 2025
모든 프로젝트들에는 공통적으로 사용되는 기능들이 있다. Expo 프로젝트도 마찬가지이다. 예를 들면 모든 앱에는 스플래시 스크린이 존재한다. 이를 수정/변경할 방법이 필요할 수 밖에 없다. 모든 모바일 기기에는 시간, 배터리 잔량 등이 표기되는 상단바(상태창)가 있다. 이 역시 대부분의 경우 통제할 수 있기를 원할 것이다. 그 밖에 화면이동(Navigation)도 있다. 화면이 1개 밖에 없는 앱은.. 존재하기는 할까?
따라서 이 글에서는 Expo 프로젝트 생성 및 해당 프로젝트에 필수적이라 생각되는 라이브러리들을 추가하는 것까지를 기록한다.
개발 환경 구성 - 1
Expo는 React Native 라이브러리이기에, nodejs 설치가 필요하다. 이 설치는 다들 알다시피 매우 간단하다. 그러나 Expo 앱(= 모바일 앱) 개발을 위해서는 좀 더 많은 환경 설정이 필요하...다? 왜 의문형이냐면 사용하지 않을 수도 있긴 하거든..
무슨 소리냐 하면 에뮬레이터 이야기다. 높은 확율로 앱 개발시, 테스트 용도로서 에뮬레이터를 사용하길 원할 수 있다. 이를 위한 준비 역시 그리 어려운 것은 아니나, 그래도 nodejs 설치와 달리 조사 및 기록이 필요한 수준은 된다고 본다.
이를 위한 기록을 직접.. 남길 수도 있지만, 사실 너무 정리가 잘되어 있으며 공신력도 있는 곳이 존재한다. 바로 React Native 공식문서이다.
이 주소로 이동해, 찬찬히 한 단계씩 따라가면 에뮬레이터 설치까지의 개발 환경 구성을 달성할 수 있을 것이다.
Tip. 나는 Android studio 실행시, 항시 Manager 창이 오픈되는 것을 좋아한다(default: open last project). 이 기능을 원한다면 다음 설정을 하도록 하자
Settings -> Appearance & Behavior -> System Settings -> Un-check "Reopen last project on startup" -> apply
개발 환경 구성 - 2
VS Code를 사용하지 않는다면 넘어가자. VS Code를 사용하더라도 넘어가도 좋다(?).
https://docs.expo.dev/develop/tools/#expo-tools-for-vs-code
Expo Tools is a VS Code extension to improve your development experience when working with app config files.
It provides features such as autocomplete and intellisense for files such as app config, EAS config, store config and Expo Module config files.
위와 같이 Expo 공식문서에서 VS Code 사용시에는 Expo Tool extension을 사용을 추천한다. 솔직히 나도 아직 득을 보진 못했는데.. 그냥 설치해주는 편이다.
프로젝트 생성
이제 위 문서를 참고해 프로젝트 생성하면 된다. 더 할말이.. 있다. 글 작성 시점 기준, 기본 설치 명령어(npx create-expo-app@latest)를 실행하면 자동으로 기본 내용이 작성되어 있는 프로젝트(Default)가 생성된다. 나는 이를 좋아하지 않는다. 따라서 내 경우에는 --template 명령어를 추가해 실행한다. 그럼 다음과 같은 선택지들을 확인할 수 있다.
Default / Blank / Blank (TypeScript) / Navigation (TypeScript) / Blank (Bare)
이 중에서 나는 Blank (TypeScript) 를 필요한 패키지를 추가하는 방법을 사용한다. 지금와 생각하면 Navigation (TypeScript) 템플릿은 내가 추가하고자 하는 대부분의 패키지가 추가된 상태이기에, 이를 선택 후 조금만 삭제/추가/변경해도 되었을 것으로 본다. 그러나 나는 이 패키지 추가 후 필요한 설정을 위해 프로젝트를 변경해 나가는 것도 학습의 일종이라 생각하기에, 앞으로도 이 방법을 고수할 것이다.
Blank를 선택시, TypeScript조차 설치되어 있지 않다. 이때는 https://reactnative.dev/docs/typescript 를 참조해 추가하면 된다. 이 또한 학습이니 좋다. 내 경우는 Blank (TypeScript) 선택함으로 이 부분은 생략한 셈이다.
라이브러리 추가
프로젝트를 생성했으니 이미 앱이 구동될 수 있는 상태이다. 글 작성 기준, 프로젝트 생성시 기본 설치되어 있는 라이브러리들은 다음과 같다.
dependencies: "expo" , "expo-status-bar" , "react" , "react-native"
devDependencies: "@types/react" , "typescript"
Blank (TypeScript) 를 선택했기에 매우 단출하다. 하지만 Blank 선택에도 불구하고, 이미 상단바(상태창) 통제를 위한 expo-status-bar 패키지가 자동 추가되어 있다. 그만큼 왠만해선 필요하다는 뜻이다. 그럼 이제 이를 제외한, 나머지 필수적인 라이브러리들을 설치하도록 하자.
조만간 expo-status-bar 는 필수가 아니라고 판단할 것도 같다. edge-to-edge 가 Android 15 이상, target - SDK 35 이상인 경우 자동 적용되게 되면서, 상태창 관리의 주요 기능인 backgroundColor, translucent 들이 기능하지 않게 되었기 때문이다.
react-dom
react-dom은 웹 브라우저의 DOM(Document Object Model)을 조작/관리하는 역할을 한다. 그렇기에 Expo를 웹으로 사용하지 않겠다면(=모바일만 사용하겠다면), 사실 필요 없다.
그.러.나. Expo는 web 환경도 지원하는 라이브러리다. 그렇기에 추가하고자 하는 Expo 패키지가 web 환경을 지원한다면 자동으로 react-dom을 설치하려고 한다. 그럼 설치하게 두면 되지 뭐가 문제냐.. 이놈들이 내 프로젝트의 react버전을 보지 않고, 본인들이 선언해 놓은 버전? or 패키지 최신 버전의? react-dom을 설치하려 한다는 것이다 ㅡㅡ.
React와 React-DOM은 함께 작동하는 라이브러리이므로, 호환성을 위해 같은 버전(or 같은 피어 종속성 범위)을 유지하는 것이 일반적이다. 그런데 위와 같은 상황이 발생하면? 더 상위 버전의 react-dom을 설치를 시도하는 셈이 되어 버리고, 이는 현재 프로젝트에 설치되어 있는 react와 버전이 맞지 않다는 Conflicting peer dependency 오류와 함께 설치가 종료된다. --force 명령어를 추가해 강제 설치할 수도 있지만, 개인적으로 매우 좋지 않은 방법으로 생각한다.
결론은 Expo 프로젝트를 모바일에서만 사용할 예정이더라도, react-dom은 프로젝트의 react와 같은 버전으로 선제적 설치하는 것이 속 편하다고 생각한다.
expo-splash-screen
모든 모바일 앱이라면 스플래시 스크린을 관리하는 방법은 필요하다고 단언할 수 있다.
expo-dev-client
Expo 앱 개발은 Expo Go를 이용하느냐 Development build를 사용하느냐로 구분된다. 그리고 나는 모든 앱은 Development build를 사용하는게 맞다고 생각하는 사람이다. expo-dev-client는 아래와 같은 기능을 통해, 개발에 편의성을 더해준다.
- Hot Reloading/Fast Refresh: 코드 변경 시 즉시 앱에 반영
- 개발자 메뉴: 디버깅, 로그 확인, 번들러 재시작 등의 도구에 접근
- 번들러 연결: Metro Bundler와 디바이스 앱 간의 연결 관리
물론 Development build를 사용하더라도, 설치하지 않아도 되긴 하다. 그러나 굳이..?
- 설치 O + development build 사용 => npx expo start => Metro bundler: development build 모드로 시작 => 정상
- 설치 X + development build 사용 => npx expo start => Metro bundler: Expo Go 모드로 시작 => 오류
- 설치 X + development build 사용 => npx expo start --dev-client => Metro bundler: development build 모드로 시작 => 정상
expo-router
거의 모든 앱에는 2개 이상의 페이지가 존재한다. 즉, 페이지 이동을 제어할 방법이 필요하다는 뜻이다. 직접 구현해볼 수도 있겠지만, 이미 너무 잘 만들어진 기능들이 존재한다.
대표적으로 React Navigation이 있으며, 나도 이전에는 이를 활용했다. 그러나 이제 Expo Router도 개발된지 오래되어 최적화가 되었을 것으로 예상되며, 무엇보다 Expo 앱이니.. 좀 더 잘 맞지 않을까 기대한다. 무엇보다 Expo router는 결국 React Navigation을 상속해 개발되었으며, 그 기능들이 여전히 사용가능하기에 사용하지 않을 이유가 없다.
앞서의 패키지들과 달리, expo router는 설치 후 프로젝트에 변경해야할 내용들이 있다. 상세한 내용은 https://docs.expo.dev/router/installation/ 를 참조해 진행하자.
위 링크에는 없는 내용으로, app.json 파일에 플러그인 설정을 추가해야할 필요가 있다.
https://docs.expo.dev/versions/latest/sdk/router/
그러나 작성일 기준, 패키지 설치시 자동으로 추가되긴 하였다.
나는 보통 Drawer 사용을 위한 패키지도 설치한다. 필수는 아니나, 많은 앱에서 이용하는 디자인인 만큼 나쁜 선택은 아닐 것이다
https://docs.expo.dev/router/advanced/drawer/
만일 Drawer 설치를 진행했다면, 작성일 기준 빌드시, Expo doctor가 react-native-gesture-handler가 없다는 경고를 발생할 수도 있다. SDK 54 이후 버전은 react-native-worklets을 대신 설치하라고 안내함에도 불구하고 말이다. 이는 Expo doctor가 업데이트되지 않았거나.. @react-navigation/drawer 패키지에서 여전히 react-native-gesture-handler를 peer dependency로 요구하고 있는 것으로 짐작된다. 이것이 거슬린다면 그냥 설치해주도록 하자..
위 내용들로 설치는 완료되었다. 그러나 지금 앱을 실행하면 오류가 발생한다. 이는 Expo router 사용을 위해 진입점 변경 설정은 하였지만, 실제 진입점을 만들어주지 않았기 때문이다. 따라서 아래 내용을 진행하도록 하자.
-
기존 App.tsx, index.ts 파일 삭제 (더이상 사용되지 않음) (삭제하기 싫으면, 유지해도 문제는 없다... 근데 굳이?)
-
신규 폴더 및 파일 생성 : app/index.tsx
-
(선택사항) 상위에 src 폴더 구성 => src/app/index.tsx
개인적으로는 src폴더를 구성해, 앱관련 내용은 모두 src 하위에 두는 것이 정리된 느낌이라 좋아한다. 알다시피 src 폴더는 많은 프로젝트에서 사용되는 폴더명이기에, Expo가 예외로 허용해주는 것이다. 다른 이름의 폴더를 app폴더 상위에 두면 에러가 발생한다.
이를 마치면, 다시 정상 작동한다. 추후 어떤 방식으로 route를 진행해야 하는지는 공식문서에서 학습하도록 하자.
react-native-safe-area-context
expo-status-bar의 translucent 기능이 없어지고 edge-to-edge가 자동적용됨에 따라, UI가 기본적으로 상태창과 겹치는 상태가 되게 되었다. 경우에 따라 유용히 활용하기도 하겠지만, 그러한 디자인을 원치 않는 상황도 많을 것이다. 이를 위해서는 시스템 UI들이 배제된 영역을 구해야 하는 상황이다.
이 패키지를 사용하면 간단히 목적 달성이 가능하다. 패키지가 제공하는 SafeAreaView로 상단을 감싸주기만 하면, 상태창은 물론 하단 네비게이션바 영역도 고려한, 시스템 UI와 중첩되지 않은 영역을 사용할 수 있다.
이 패키지는 이 글을 순서대로 따라왔다면 별도 설치할 필요가 없다. expo-router 설치 단계에서 함께 설치되었을 것이다.
@expo/vector-icons (선택)
이 패키지는 다양한 아이콘들을 제공할 뿐이다. 따라서 필수는 아니나.. 아마 대부분의 앱은 간단한 아이콘 표출을 사용할 가능성이 많기에, 나쁘지 않은 선택지가 되어줄 것이다.
EAS 설정 (선택)
EAS는 Expo에서 제공하는 서비스로 여러 기능이 있다. 현 단계에서 EAS를 사용하려는 이유는 EAS build를 사용하기 위함이다. 만일 로컬 build를 선호한다면 이 단계는 넘겨도 무방하다.
내가 이를 사용하는 이유는.. iOS 빌드가 가능하다는 이유가 크다. 내 개발환경은 window이기에 iOS 빌드를 직접 진행하려면, 많은 편법을 거쳐야 하며 좋지도 않다. 따라서 나와 같은 경우라면, EAS build를 이용하는 방법을 추천한다.
기본 설정 및 사용법은 아래 공식문서를 참고하자.